.\" $OpenBSD: BIO_find_type.3,v 1.12 2023/07/26 20:01:04 tb Exp $
.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\"
.\" Copyright (c) 2021, 2023 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2000, 2013, 2016 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: July 26 2023 $
.Dt BIO_FIND_TYPE 3
.Os
.Sh NAME
.Nm BIO_find_type ,
.Nm BIO_next ,
.Nm BIO_method_type ,
.Nm BIO_method_name
.Nd BIO chain traversal
.Sh SYNOPSIS
.In openssl/bio.h
.Ft BIO *
.Fo BIO_find_type
.Fa "BIO *bio"
.Fa "int type"
.Fc
.Ft BIO *
.Fo BIO_next
.Fa "BIO *bio"
.Fc
.Ft int
.Fo BIO_method_type
.Fa "const BIO *bio"
.Fc
.Ft const char *
.Fo BIO_method_name
.Fa "const BIO *bio"
.Fc
.Fd #define BIO_TYPE_NONE		0
.Fd #define BIO_TYPE_START		128
.Sh DESCRIPTION
.Fn BIO_find_type
searches for a BIO matching the given
.Fa type
in the chain starting at
.Fa bio .
If the least significant byte of the
.Fa type
argument is non-zero, only exact matches of the
.Fa type
are accepted.
Otherwise, a match only requires that any of the bits set in the
.Fa type
argument is also set in the candidate BIO.
.Pp
Types with a least significant byte in the range from 0 to
.Dv BIO_TYPE_START ,
inclusive, are reserved for BIO types built into the library.
Types with a least significant byte greater than
.Dv BIO_TYPE_START
are available for user-defined BIO types; see
.Xr BIO_get_new_index 3
for details.
.Pp
.Fn BIO_next
returns the next BIO in the chain after
.Fa bio .
This function can be used to traverse all BIOs in a chain
or in conjunction with
.Fn BIO_find_type
to find all BIOs of a certain type.
.Pp
.Fn BIO_method_type
returns the type of the given
.Fa bio .
.Pp
.Fn BIO_method_name
returns an ASCII string representing the type of the
.Fa bio .
.Pp
The following are the built-in source/sink BIO types
that operate on file descriptors.
They all have both of the bits
.Dv BIO_TYPE_SOURCE_SINK
and
.Dv BIO_TYPE_DESCRIPTOR
but not the bit
.Dv BIO_TYPE_FILTER
set in their type constant.
.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3)
.It Fa type No constant   Ta Em name No string Ta Vt BIO_METHOD
.It Dv BIO_TYPE_ACCEPT      Ta socket accept   Ta Xr BIO_s_accept 3
.It Dv BIO_TYPE_CONNECT     Ta socket connect  Ta Xr BIO_s_connect 3
.It Dv BIO_TYPE_DGRAM       Ta datagram socket Ta Xr BIO_s_datagram 3
.It Dv BIO_TYPE_FD          Ta file descriptor Ta Xr BIO_s_fd 3
.It Dv BIO_TYPE_SOCKET      Ta socket          Ta Xr BIO_s_socket 3
.El
.Pp
The following are the built-in source/sink BIO types
that do not directly operate on file descriptors.
They all have the bit
.Dv BIO_TYPE_SOURCE_SINK
but not the bits
.Dv BIO_TYPE_DESCRIPTOR
and
.Dv BIO_TYPE_FILTER
set in their type constant.
.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3)
.It Fa type No constant   Ta Em name No string Ta Vt BIO_METHOD
.It Dv BIO_TYPE_BIO         Ta BIO pair        Ta Xr BIO_s_bio 3
.It Dv BIO_TYPE_FILE        Ta FILE pointer    Ta Xr BIO_s_file 3
.It Dv BIO_TYPE_MEM         Ta memory buffer   Ta Xr BIO_s_mem 3
.It Dv BIO_TYPE_NULL        Ta NULL            Ta Xr BIO_s_null 3
.El
.Pp
The following are the built-in filter BIO types.
They all have the bit
.Dv BIO_TYPE_FILTER
but not the bits
.Dv BIO_TYPE_SOURCE_SINK
and
.Dv BIO_TYPE_DESCRIPTOR
set in their type constant.
.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3)
.It Fa type No constant   Ta Em name No string Ta Vt BIO_METHOD
.\" BIO_TYPE_ASN1 is intentionally undocumented because BIO_f_asn1 was
.\" removed from the public API.
.\" .It Dv BIO_TYPE_ASN1        Ta asn1            Ta Xr BIO_f_asn1 3
.It Dv BIO_TYPE_BASE64      Ta base64 encoding Ta Xr BIO_f_base64 3
.It Dv BIO_TYPE_BUFFER      Ta buffer          Ta Xr BIO_f_buffer 3
.It Dv BIO_TYPE_CIPHER      Ta cipher          Ta Xr BIO_f_cipher 3
.It Dv BIO_TYPE_MD          Ta message digest  Ta Xr BIO_f_md 3
.It Dv BIO_TYPE_NULL_FILTER Ta NULL filter     Ta Xr BIO_f_null 3
.It Dv BIO_TYPE_SSL         Ta ssl             Ta Xr BIO_f_ssl 3
.El
.Pp
The constants
.Dv BIO_TYPE_BER ,
.Dv BIO_TYPE_PROXY_CLIENT ,
and
.Dv BIO_TYPE_PROXY_SERVER
do not correspond to any BIO types implemented by the library and are
not intended to be used for application-defined types, either.
The constants
.Dv BIO_TYPE_COMP ,
.Dv BIO_TYPE_LINEBUFFER ,
and
.Dv BIO_TYPE_NBIO_TEST
corresponds to a deprecated BIO types that are intentionally undocumented.
.Pp
If a variable in an application program is intended
to store a BIO type but temporarily does not refer to any BIO
or refers to a BIO of an unknown type, setting the variable to
.Dv BIO_TYPE_NONE
is recommended.
.Sh RETURN VALUES
.Fn BIO_find_type
returns the next matching BIO or
.Dv NULL
if
.Fa bio
is a
.Dv NULL
pointer or if no matching BIO is found.
.Pp
.Fn BIO_next
returns the next BIO or
.Dv NULL
if
.Fa bio
is a
.Dv NULL
pointer or points to the last BIO in a chain.
.Pp
.Fn BIO_method_type
returns one of the
.Dv BIO_TYPE_*
constants.
.Pp
.Fn BIO_method_name
returns an internal pointer to a string.
.Sh EXAMPLES
Traverse a chain looking for digest BIOs:
.Bd -literal -offset 2n
BIO *btmp;

btmp = in_bio;	/* in_bio is the chain to search through */
while (btmp != NULL) {
	btmp = BIO_find_type(btmp, BIO_TYPE_MD);
	if (btmp == NULL)
		break;	/* Not found */

	/* btmp is a digest BIO, do something with it ... */
	...

	btmp = BIO_next(btmp);
}
.Ed
.Sh SEE ALSO
.Xr BIO_meth_new 3 ,
.Xr BIO_new 3
.Sh HISTORY
.Fn BIO_method_type
and
.Fn BIO_method_name
first appeared in SSLeay 0.6.0.
.Fn BIO_find_type
first appeared in SSLeay 0.6.6.
These functions have been available since
.Ox 2.4 .
.Pp
.Fn BIO_next
first appeared in OpenSSL 0.9.6 and has been available since
.Ox 2.9 .
